docs: Add a note on the "presentation" role

diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md
index efafadd512d80b46c14b17e7e1b14e022cc86274..b86aac419be41de1bc3e6c763e7a8ad4f4c6982e 100644 (file)
--- a/docs/reference/gtk/section-accessibility.md
+++ b/docs/reference/gtk/section-accessibility.md
@@ -292,6 +292,20 @@ The power of hiding and enhancing can be a double-edged sword, as it can
 lead to inadvertently overriding the accessible semantics of existing
 widgets.
 
+## Hiding UI elements from the accessible tree
+
+The accessibility API is mainly used to express semantics useful for
+assistive technologies, but it can also be used to hide elements. The
+canonical way to do so is to use the %GTK_ACCESSIBLE_ROLE_PRESENTATION,
+which declares that a UI element is purely meant for presentation purposes,
+and as such it has no meaningful impact on the accessibility of the
+interface.
+
+A "presentation" role should not be confused with the
+%GTK_ACCESSIBLE_STATE_HIDDEN state; the "hidden" state is transient, and is
+typically controlled by showing and hiding a widget using the #GtkWidget
+API.
+
 ## Design patterns and custom widgets
 
 When creating custom widgets, following established patterns can help